FOCUS

A FOrm-based Customizable User Shell

No warranty is provided. Use this code AS-IS. Also, no support is provided, although the author will make a good attempt to provide helpful feedback.

(All that aside, what I'm really concerned about is making sure that any revisions to this code come through me. Not that I'm expecting a huge amount of use, but . . . :)

User Documentation authored 7/9/93
James Eric Tilton
Willamette Integrated Technology Services

Introduction

Focus is perhaps unique, in that it provides a unified screen-based environment for users in a unix environment, using the curses library. This means that friendly interfaces and "infostructures" can be provided for users who only have access to VT100 terminal emulation, or other similar kinds of text-based displays. While it certainly doesn't provide a fully-functional windowing environment, it does provide a consistent environment to run other applications from -- as well as allowing many unix commands to be executed without ever having to leave the Focus environment.

What is a form? A form is, essentially, a description of a screen. A form can contain four kinds of information:

• straight text
• editable text fields
• text fields with a finite number of preset values
• "buttons" which can perform some sort of action

• non-editable text fields
• fields which require a value
• fields for which the entered value must fulfill a specific requirement
• default values
• variables
• dialog boxes, selection boxes, and display boxes
• conditionally invisible lines

Using Focus

jupiter% focus

This form (known as the "home form") provides a launching pad for Focus sessions.

Job Control

[No further user documentation exists. If there is a real demand for this program, and a real freeing-up of my time, more might possibly be created.]

Forms can be in one of two places -- either in the user's personal directory (~/forms, unless otherwise specified in the environment variable FORMDIR), or in the system-wide form directory. The FOCAL interpreter engine (Focus) will look first in the user's form directory, and then in the system-wide form directory. Every form is specified by a unique file name (and so, a user can replace a system form with a personalized form by placing a form of the same name in her own form directory).

A form consists of lines -- each line will contain either a directive, a variable assignment, a comment, text, or a button or field description of some sort, as described below. Lines are terminated by carriage returns.

Directives

Form Title

This directive allows a title to be specified for the form. This title will be displayed centered, and in reverse video, on the top of the screen. It will not appear in any output to actions.

If no title is specified, the title "(Untitled)" will be displayed.

Variable substitution in this directive is not supported.

Example:
#form: File Utilities

RFC822 Headers

This pair of directives provide for the automatic mailing of a form, without having to specify an explicit action. When the "#to:" directive is supplied, than the ^X command will mail the form to the address given. If a "#subject:" line is provided, then it will be used as the subject for the mailing list.

No variable substitution is currently possible with these directives, though support for this may eventually be added.

Action of the Form

This directive allows an action to be associated with the form (for a description of actions, see below).

Form to Replace With

This directive takes the file name of another form. Upon closing this form, the new form is to be opened, before returning to the original form. Essentially, the current form is popped off of the stack of forms, and the new form is pushed onto the top of the stack. In this way, a directed sequence can be created.

This directive is not recommended for habitual use -- it disrupts the normal flow of navigation, and can be confusing unless used with care. One possible use might be to have a series of pages of nothing but text, linked together by a trail of "#replace" directives. Since pressing the space bar will normally cause you to return from a form that has no fields or buttons, you can use this as a pseudo-paging mechanism.

Once again, there is no variable substitution support.

New Group of Fields

This directive is for the formatting of editable text fields. Normally, all text fields in a group will share the same left margin, like so:

Name:         [                                            ]
Phone Number: [                                            ]
Address:      [                                            ]
Age:          [                                            ]

Name:         [                                            ]
Phone Number: [                                            ]
Address: [                                                 ]
Age:     [                                                 ]

Variable Assignment

$variablename = new variable value

For example,

$phonenumber = 555-4BOB

If the new value given begins with a '$', then the variable is assigned the value of whichever internal variable is specified. If the new value begins with a '%', then the appropriate environment variable is used.

Note: If the variable "$debug" is set to "true", then Focus will run in debugging mode. (For now, this simply means that the ^G help screen will display a list of currently assigned variables).

Also, Focus uses the value of the $shell variable to determine which shell to invoke upon a ^N or '!'. It may be desirable to include the line

$shell = %shell

in your home form.

Straight Text

Straight text is used for descriptions and explanations for the user, or for providing formatting information for actions.

Straight text can come in three flavors, providing the form designer with a way of having text which might only appear in the form, or only appear in the mailed version:

• If there is no special character in the first position, then it is both printed to the screen, and considered part of the standard output to actions.
• If there is a "<" as the first character, the text will only be used as standard output, and never be displayed on the screen. (For example, "For Office Use Only:" kinds of text could be placed here.)
• If there is a ">" as the first character, the text is only displayed on the screen, and never sent to the standard output. Help for the user can be placed on such a line (so that, if you were to mail the form, the "unimportant" help information won't be mailed as well).

Editable Text Field

{conditional visibility expression} Field Title [Default Value] : width > $storage {verification expression} (action) ;comment

(all on one, unbroken line.) However, the simple version is:

Field Title [Default Value]

Note that everything is optional -- the only essential requirement for a field is that the "[" and "]" characters are contained within it. A simple description of a field might be:

Name: []

Which would show up on the screen as

Name: [                                                     ]

Name:[] : 5

which would give you:

Name: [     ]

You can also specify a default value, which can consist of both text and variables. To delimit blocks of text from variables, use the comma. So:

Name: [John Smith] would become

Name: [John Smith                                           ]

Name: [$middlename]

would, if $middlename was equal to "Bob", become

Name: [Bob                                                  ]

Name: [John , $middlename, Smith]

would become

Name: [John Bob Smith                                       ]

Also, if you want to store the contents of the field into an internal variable, you would use the syntax

Name: [] > $name

Whenever a FOCAL interpreter engine, such as Focus, executes an action, it will first store whatever value is in the "Name:" field into the internal variable $name. This ensures that any internal variable substitutions in actions associated with the form will reflect the current state of the form.

Verification expressions, conditional visibility expressions, and actions are covered below.

Toggle Fields

{conditional visibility expression} Field Title [#toggle:Default Value1, Default Value2, ...] : width > $storage {verification expression} (action) ;comment

(all on one, unbroken line.) Note that the only difference in format between this and an editable text field is that the default values must be specified, and that a field directive of #toggle: is provided.

Toggle field default values are delimited by the comma. White space after the comma (or the #toggle:) is ignored.

An example text field is:

T-Shirt Size: [#toggle: small, medium, large]

This will display on the screen identically to an editable text field with the default value "small". However, when the field is selected by the user, it will change it to a horizontally scrollable field, presenting the three options.

Note that there is no variable substitution allowed in the default values of a toggle field. However, if a toggle field specifies a storage variable, then the FOCAL interpreter engine should check the value of that storage variable and attempt to find a matching value among the choices. It should then present that choice as the currently selected value. So, for instance,

Default Shell: [#toggle: csh, sh, bash] > $shell

Will present "sh" as it's current value if $shell is set to equal "sh". (Note: if $shell is set to a value that is not equal to any of the values of the toggle field, then the field will display the current value of $shell upon opening of the form. However, once the field is selected, the first default value will be selected, and then subsequently stored in the internal variable.)

Buttons

The format of a button field is

{conditional visibility expression} [#button: Button Name 1 (button action 1), Button Name 2 (button action 2), ...]

(all on one, unbroken line.) Note that the major difference in format between this and the other types of fields: first, the #button: field directive, and the mandatory actions associated with each button. Also, there is no field title specified (one can be specified, but the FOCAL interpreter engine is not required to provide for its display). Similarly, the width and storage specifications are not supported.

Finally, there is no verification expression, as there is no value to verify, and there is no field action, as they are associated with the buttons themselves (and not with the line). Buttons are intended as the most obvious method of performing actions -- while they can be performed from other types of fields (and the field itself), they can be most intuitively presented with an on-screen control such as the button. Actions are mainly provided in fields and forms in order to provide short-cuts, as well as to enable intelligent selection of appropriate values for the field (more on this in the section on verification expressions).

Actions will be explained in the next section, but a simple example of buttons is:

[#button: Pine (pine -z), News (trn -a -x -X)]

Which will provide a line something like:

                 (Pine)                       (News)

Actions

The normal syntax of an action is:

(#name# infilter | command | outfilter )

where name, infilter, and outfilter are optional.

Note: although in field and button descriptions, an action is delimited by (), there is no such delimiting in the #result: directive. For the #result: directive, the syntax is

#result: #name# infilter | command | outfilter

We will cover, in turn, what is a valid value for name, infilter, outfilter, and command.

Name

For example, an action might be associated with a text field -- perhaps by invoking the action with ^D, the user can spell check the word in the field. In that case, it would be nice to be able to alert the user to this possibility. To do that, you might use a line like:

Enter a word: [] (#Spellcheck# spellcheck $checkword | select)

(where 'spellcheck' would be a program which would return a 1 or 0 based on whether the word provided was spelled correctly)

In this example, when the cursor was in this field a line would be displayed at the bottom of the screen something like: "^D Spellcheck".

(Warning -- the parser may choke if you have weird names in between the ##'s. So check there if you have problems.)

Infilters

An infilter can be any of the following:

• nothing
• this
• filter filter1, filter2, ...
• all

The "this" infilter supplies, as standard input to the command, the value of the field which this infilter is associated with. The value includes the field name, as well as the field value that has been entered (formatted as it would appear on the screen, except without the surrounding square brackets -- "[]").

The "filter" infilter supplies the values of the fields which match the given filters. Matching is similar to a "egrep -i ^filter1 |^filter2 |...", in that it is case insensitive, and attempts to match from the beginning of the value. Effectively, this means that you can match by field title (since this is the beginning of the value). So, "filter name address" would feed the name and address fields through the standard input to the command (as well as the "addressing" field, should it exist╔). Note: this also supplies straight lines, should they match. This includes all straight lines that do not begin with the character '>'.

The "all" outfilter simply supplies all lines which would normally be sent to the standard input. It is similar in output to the output of the "mailform" special command. Once again, the output of a line described with "Name: []" will be "Name: Value entered in Field by User ", and the output of a straight text line will be itself. Lines containing buttons and lines preceded by the character ">" will never be part of the standard input.

Example:

Given the following form description:

#form: Test From
This is a test form.
>This line only goes to the screen.
<This line only goes to the standard input of an action.
Name: []
Phone: []
Platform: []

For this, if the cursor is in the "Name:" field:

Name:     John Smith

This line only goes to the standard input of an action.
Name:     John Smith
Phone:    555-QZQZ
Platform: Unix

Name:     John Smith

Outfilters

An outfilter can be any of the following:

• discard
• display
• select
• update [$internalvar1, $internalvar2, ...]
• interactive

The "display" outfilter reads in the standard output of the command, and displays it in a window on the screen. The user will be able to scroll through the window, if its contents are larger than the screen. The output will also be formatted into multiple columns, if possible.

The "select" outfilter is like the "display" outfilter, except the user has the opportunity to select one of the lines of the standard output. If this is an outfilter for an action in an editable text field, then whatever line is selected replaces the contents of that text field. (One use for this would be to select a valid value for a field, from a list of possible values, such as a list of usernames).

The "update" outfilter has two incarnations. If no internal variable names are specified, then it expects a standard output of the form:

$variable1 = value1
$variable2 = value2
....
$variableX = valueX

However, if the outfilter specifies internal variables (for ex. "update $name $phone"), then it will assign each of those variables a value for the standard output of the command. If possible, the first line of the standard output will be placed in the first variable specified, the second into the second, and so forth. (If there are more variables specified then lines of output, or vice versa, then the excess will be ignored.)

The "interactive" outfilter will turn control of the terminal over to the specified command. Infilters are ignored, and the output of the program does not modify the form in any way. You can use this to, say, launch a gopher session by placing a button labeled "(Gopher)" on your form, and associating the action (gopher | interactive) with it. The syntax for this example would be:

[#button: Gopher (gopher | interactive)]

Commands

• cd
• invoke formname
• replace formname
• mailform

"invoke" opens another form onto the form stack. When the form formname is closed, control returns to the current form.

"replace" closes the current form, and opens the form formname.

"mailform" mails the current form, identically to the result of the "#to:" directive (described above). (This is useful if you want to provide a "(Mail this Form)" button)

A command can contain internal variables. If it does, then the values of the internal variables are substituted as arguments. For example, the command "ls $directory" will evaluate to:

ls foobar (if $directory = "foobar") or

ls "Grand Canal" (if $directory = "Grand Canal").

Note that the quotes merely represent the fact that "Grand Canal" is all one argument to "ls". Focus does not yet actually support quoting, and spaces will normally delimit arguments. However, argument delimiting takes place before variable substitution, so any spaces in variable value will not break that value up into separate arguments.

Also, note any field values that are to be stored in internal variables are stored before the command is invoked.

Verification Expression

If a verification expression is supplied for a field, then that verification expression is evaluated everytime the user attempts to leave the field. If the command returns a value of 0 (not on the standard output, mind you, but actually returns it), then the condition evaluates as true. Anything other than 0 evaluates as false.

If a verification expression evaluates as false, then the action for that field is invoked. The user is not allowed to leave the field until the verification expression evaluates as true.

One example use of a verification expression might be:

Name: [$name] > $name {finduser} (validusers $name | select)

When the user attempts to leave the field "Name:", the program "finduser" is invoked. This hypothetical program reads the first line of its standard input and finds "John Smith" there. It checks its list of valid users, and see that John Smith is not on that list. It then returns a 1.

The FOCAL interpreter engine sees that the result of this operation was not 0, and invokes the command for the field. The command "validusers "John Smith"" is invoked. This hypothetical program takes the single argument "John Smith", and produces a list of close matches on its standard output.

The FOCAL interpreter engine then allows the user to select one of the values returned by "validusers". It then places this value into the "Name:" field. Control returns to the user, with the cursor still placed in the "Name:" field.

Note that a verification expression, like a command, supports internal variable substitution. Passing the value on the command line (for example, finduser $name) is also a desirable way of implementing the above example.

Conditional Visibility Expression

A conditional visibility expression is evaluated only upon opening a form -- should it evaluate to true, then that particular line is displayed on the screen. Should it evaluate to false, that line is not displayed on the screen.

CVE's might be used in order to provide certain options only to qualified users, or to otherwise customize the appearance forms based on the needs, abilities, or priveleges of users.

Plans for the Future

• Job control (exists now. caveat emptor. use ^Z and ^F.)
• Piping, with filters like "select" includable in pipes
• Mail checking
• Better handling of error messages (stderr)
• Scripting?
• Have verifyvalue() be able to deal with $vars

Glossary

Action

An interface for calling external unix functions. An action usually takes the form (infilter | command | outfilter), where the infilter specifies what standard input is fed to the command, and the outfilter specifies how the standard output should be handled.

The command is usually a unix command, although it can be one of several built-in commands as well (for these, the in and outfilters are usually ignored). The command can also contain (recursive!) descriptions of the various kinds of dialog boxes, and variables which will be substituted.

Focal

a FOrm Composition Almost-Language. Focal is the language in which forms are described. Somewhat classically baroque, Focal is extremely easy to use to create simple forms, but also can be excessively complex when trying to utilize the more advanced features. Some tricks to power-using Focal are described within this document.

Focus

The FOrm Customizable User Shell, or, alternately, a Friendly Online Computer User Shell, whatever. Focus interprets forms created in Focal, and presents them on the screen in an interactive manner. Details on using Focus are contained within this document. Note that, while Focus was originally designed as form-processing program, it can, with it's current extensions, be used as a generic screen interface to just about any unix program.

Form

a "smart" screen description. A form provides an interactive interface for the user to enter information, and perform various actions. Forms are the building blocks of Focus hyperspaces.

Hyperspace

Inspired by Vannevar Bush's 1945 vision of the Memex in his article, "As We May Think", and etymologically and conceptually descended from Ted Nelson's visions of "hypertext" and "hypermedia", a hyperspace is a space connected in a non-linear fashion by references and pointers. It is the opinion of the author that any good infostructure will also be a hyperspace, because it encourages the explorer to search after the information that is immediately interesting, but be able to find their way back to the original task.

Infostructure

A word coined by the author to describe any navigable arrangement of pointers to other references. While an infrastructure provides the low-level support which is often invisible to users, an "infostructure" provides the basic navigation aids to help the user find the information she or he is looking for, or to help sort through the deluge of the information which the user is often subjected to. Gopher-space is an infostructure, as is the World-Wide-Web. In the non-high-tech milieu, bibliographies and library catalogs are also examples of infostructures.